---
title: Next.js
description: How to use HeroUI with Next.js
---

# Next.js


Requirements:

- [Next.js 12](https://nextjs.org/) or later
- [React 18](https://reactjs.org/) or later
- [Tailwind CSS v4](https://tailwindcss.com/docs/installation/framework-guides/nextjs)
- [Framer Motion 11.9](https://www.framer.com/motion/) or later

------

<CarbonAd/>

To use HeroUI in your Next.js project, you need to follow the steps below, depending on your project structure.

## App Directory Setup

Next.js 13's `app/` directory uses Server Components by default. HeroUI components can be imported directly in Server Components since we add `use client` at build time.

### HeroUI CLI (recommended)

If you are starting a new project, you can use the HeroUI CLI to create a new project with HeroUI pre-configured:

<Spacer y={4}/>

```bash
npx heroui-cli@latest init -t app
```

or

<PackageManagers
  commands={{
    npm: 'npx heroui-cli@latest init -t app',
    yarn: 'yarn dlx heroui-cli@latest init -t app',
    pnpm: 'pnpm dlx heroui-cli@latest init -t app',
    bun: "bunx heroui-cli@latest init -t app"
  }}
/>

### create-next-app 

If you are starting a new project, you can run one of the following commands to create a Next.js project pre-configured with HeroUI:

<PackageManagers
  commands={{
    npm: 'npx create-next-app -e https://github.com/heroui-inc/next-app-template',
    yarn: 'yarn create next-app -e https://github.com/heroui-inc/next-app-template',
    pnpm: 'pnpm create next-app -e https://github.com/heroui-inc/next-app-template',
    bun: 'bunx create-next-app -e https://github.com/heroui-inc/next-app-template'
  }}
/>

### Automatic Installation

You can add individual components using the CLI. For example, to add a button component:

```codeBlock bash
npx heroui-cli@latest add button
```

This command adds the Button component to your project and manages all related dependencies.

You can also add multiple components at once:

```codeBlock bash
npx heroui-cli@latest add button input
```

Or you can add the main library `@heroui/react` by running the following command:

```codeBlock bash
npx heroui-cli@latest add --all
```

If you leave out the component name, the CLI will prompt you to select the components you want to add.

```codeBlock bash
? Which components would you like to add? › - Space to select. Return to submit
Instructions:
    ↑/↓: Highlight option
    ←/→/[space]: Toggle selection
    [a,b,c]/delete: Filter choices
    enter/return: Complete answer

Filtered results for: Enter something to filter

◯  accordion
◯  autocomplete
◯  avatar
◯  badge
◯  breadcrumbs
◉  button
◯  card
◯  checkbox
◯  chip
◯  code
```

You still need to add the provider to your app manually (we are working on automating this step).

```jsx {3,7,9}
// app/providers.tsx

import {HeroUIProvider} from '@heroui/react'

export function Providers({children}: { children: React.ReactNode }) {
  return (
    <HeroUIProvider>
      {children}
    </HeroUIProvider>
  )
}
```

<Spacer y={4} />

```jsx {6,10,12,14}
// app/layout.tsx

// globals.css includes @tailwind directives
// adjust the path if necessary
import "@/styles/globals.css";
import {Providers} from "./providers";

export default function RootLayout({children}: { children: React.ReactNode }) {
  return (
    <html lang="en" className='dark'>
      <body>
        <Providers>
          {children}
        </Providers>
      </body>
    </html>
  );
}
```

### Manual Installation

<Steps>

### Add dependencies

In your Next.js project, run one of the following commands to install HeroUI:

<PackageManagers
  commands={{
    npm: 'npm i @heroui/react framer-motion',
    yarn: 'yarn add @heroui/react framer-motion',
    pnpm: 'pnpm add @heroui/react framer-motion',
    bun: "bun add @heroui/react framer-motion"
  }}
/>

### Hoisted Dependencies Setup

<Blockquote color="primary">
**Note**: This step is only for those who use `pnpm` to install. If you install HeroUI using other package managers, you may skip this step.
</Blockquote>

If you are using pnpm, you need to add the following line to your `.npmrc` file to hoist our packages to the root `node_modules`.

```bash
public-hoist-pattern[]=*@heroui/*
```

After modifying the `.npmrc` file, you need to run `pnpm install` again to ensure that the dependencies are installed correctly.

### Tailwind CSS Setup

HeroUI is built on top of Tailwind CSS, so you need to install Tailwind CSS first. You can follow the official
[installation guide](https://tailwindcss.com/docs/installation/framework-guides/nextjs) to install Tailwind CSS.

<Blockquote color="primary">
**Note**: If you are using pnpm and monorepo architecture, please make sure you are pointing to the ROOT `node_modules`
</Blockquote>

Then you need to create `hero.ts` file

```ts
// hero.ts
import { heroui } from "@heroui/react";
export default heroui();
```

and add  the following code to your main css file:

```css
@import "tailwindcss";
@plugin './hero.ts';
/* Note: You may need to change the path to fit your project structure */
@source '../../node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}';
@custom-variant dark (&:is(.dark *));
```

### Setup Provider

Go to your `app/providers.tsx` or `app/providers.jsx` (create it if it doesn't exist) and wrap the Component with the `HeroUIProvider`:

```jsx {4,8,10}
// app/providers.tsx
'use client'

import {HeroUIProvider} from '@heroui/react'

export function Providers({children}: { children: React.ReactNode }) {
  return (
    <HeroUIProvider>
      {children}
    </HeroUIProvider>
  )
}
```

### Add Provider to Root

Now, Go to your `root` layout page and wrap it with the `Providers`:

```jsx {6,10,12,14}
// app/layout.tsx

// globals.css includes @tailwind directives
// adjust the path if necessary
import "@/styles/globals.css";
import {Providers} from "./providers";

export default function RootLayout({children}: { children: React.ReactNode }) {
  return (
    <html lang="en" className='dark'>
      <body>
        <Providers>
          {children}
        </Providers>
      </body>
    </html>
  );
}
```

> **Note**: HeroUI automatically adds two themes, `light` and `dark`, to your application. You can use any 
of them by adding the `dark`/`light` class to the `html` tag. See the [theme docs](/docs/customization/customize-theme) for more details.


### Use HeroUI Components

Now you can import any HeroUI component directly in your Server Components without needing to use
the `use client;` directive:

```jsx {2,7}
// app/page.tsx
import {Button} from '@heroui/button'; 

export default function Page() {
  return (
    <div>
      <Button>Click me</Button>
    </div>
  )
}
```
> **Important 🚨**: Note that you need to import the component from the individual package, not from `@heroui/react`. 

</Steps>

---

## Pages Directory Setup 

### HeroUI CLI (recommended)

If you are starting a new project, you can use the HeroUI CLI to create a new project with HeroUI pre-configured:

<Spacer y={4}/>

```bash
npx heroui-cli@latest init -t pages
```

If you are using the `/pages` Next.js project structure, you need to follow the steps below.

### create-next-app 

If you are starting a new project, you can run one of the following commands to create a Next.js project pre-configured with HeroUI:

<PackageManagers
  commands={{
    npm: 'npx create-next-app -e https://github.com/heroui-inc/next-pages-template',
    yarn: 'yarn create next-app -e https://github.com/heroui-inc/next-pages-template',
    pnpm: 'pnpm create next-app -e https://github.com/heroui-inc/next-pages-template'
  }}
/>

### Automatic Installation

You can add individual components using the CLI. For example, to add a button component:

```codeBlock bash
npx heroui-cli@latest add button
```

This command adds the Button component to your project and manages all related dependencies.

You can also add multiple components at once:

```codeBlock bash
npx heroui-cli@latest add button input
```

Or you can add the main library `@heroui/react` by running the following command:

```codeBlock bash
npx heroui-cli@latest add --all
```

If you leave out the component name, the CLI will prompt you to select the components you want to add.

```codeBlock bash
? Which components would you like to add? › - Space to select. Return to submit
Instructions:
    ↑/↓: Highlight option
    ←/→/[space]: Toggle selection
    [a,b,c]/delete: Filter choices
    enter/return: Complete answer

Filtered results for: Enter something to filter

◯  accordion
◯  autocomplete
◯  avatar
◯  badge
◯  breadcrumbs
◉  button
◯  card
◯  checkbox
◯  chip
◯  code
```

You still need to add the provider to your app manually (we are working on automating this step).

```jsx {3,7,9}
// app/providers.tsx

import {HeroUIProvider} from '@heroui/react'

export function Providers({children}: { children: React.ReactNode }) {
  return (
    <HeroUIProvider>
      {children}
    </HeroUIProvider>
  )
}
```

<Spacer y={4} />

```jsx {6,10,12,14}
// app/layout.tsx

// globals.css includes @tailwind directives
// adjust the path if necessary
import "@/styles/globals.css";
import {Providers} from "./providers";

export default function RootLayout({children}: { children: React.ReactNode }) {
  return (
    <html lang="en" className='dark'>
      <body>
        <Providers>
          {children}
        </Providers>
      </body>
    </html>
  );
}
```

### Manual Installation

<Steps>

### Add dependencies

In your Next.js project, run one of the following commands to install HeroUI:

<PackageManagers
  commands={{
    npm: 'npm i @heroui/react framer-motion',
    yarn: 'yarn add @heroui/react framer-motion',
    pnpm: 'pnpm add @heroui/react framer-motion',
    bun: "bun add @heroui/react framer-motion"
  }}
/>

### Hoisted Dependencies Setup

<Blockquote color="primary">
**Note**: This step is only for those who use `pnpm` to install. If you install HeroUI using other package managers, you may skip this step.
</Blockquote>

If you are using pnpm, you need to add the following line to your `.npmrc` file to hoist our packages to the root `node_modules`.

```bash
public-hoist-pattern[]=*@heroui/*
```

After modifying the `.npmrc` file, you need to run `pnpm install` again to ensure that the dependencies are installed correctly.

### Tailwind CSS Setup

HeroUI is built on top of Tailwind CSS, so you need to install Tailwind CSS first. You can follow the official
[installation guide](https://tailwindcss.com/docs/installation/framework-guides/nextjs) to install Tailwind CSS.

<Blockquote color="primary">
**Note**: If you are using pnpm and monorepo architecture, please make sure you are pointing to the ROOT `node_modules`
</Blockquote>

Then you need to create `hero.ts` file

```ts
// hero.ts
import { heroui } from "@heroui/react";
export default heroui();
```

and add  the following code to your main css file:

```css
@import "tailwindcss";
@plugin './hero.ts';
/* Note: You may need to change the path to fit your project structure */
@source '../../node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}';
@custom-variant dark (&:is(.dark *));
```

### Setup Provider

Go to pages`/_app.js` or `pages/_app.tsx` (create it if it doesn't exist) and wrap the Component with the `HeroUIProvider`:

```jsx {2,6,8}
// pages/_app.js
import {HeroUIProvider} from '@heroui/react'

function MyApp({ Component, pageProps }) {
  return (
    <HeroUIProvider>
      <Component {...pageProps} />
    </HeroUIProvider>
  )
}

export default MyApp;
```

### Use HeroUI Components

Now you can import any HeroUI component wherever you want:

```jsx {1,6}
import {Button} from '@heroui/react'

export default function Page() {
  return (
    <div>
      <Button>Click me</Button>
    </div>
  )
}
```
</Steps>
